home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1993…ch: Other People's Memory / ADC Developer CD (1993-03) (''Other People's Memory'')_iso / Dev.CD Mar 93.iso / Development Platforms / Apple II / Essentials / Technical.Notes / IIGS / TN.IIGS.083 < prev    next >
Encoding:
Text File  |  1992-07-15  |  13.7 KB  |  317 lines  |  [TEXT/GEOL]
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5. Apple IIgs
  6. #83: Resource Manager Stuff
  7.  
  8. Revised by: Matt "Even less of a middle name" Deatherage             May 1992
  9. Written by: Dave Lyons                                               May 1990
  10.  
  11. This Technical Note answers your miscellaneous Resource Manager questions.
  12.  
  13. CHANGES SINCE DECEMBER 1991:  Added several notes pertaining to System
  14. Software 6.0 and a note about making Resource Manager calls from a resource
  15. converter.  Added new discussion about how "changed" is really a resource
  16. attribute.
  17. _____________________________________________________________________________
  18.  
  19.  
  20.  
  21. UNIQUERESOURCEID
  22.  
  23. In System Software 5.0.4 and earlier, calling UniqueResourceID with an IDRange
  24. value of $FFFF does not work reliably.  It sometimes returns a system-range ID
  25. ($07FFxxxx) if there are already system-range resources of the specified type
  26. present in the current search path.
  27.  
  28. If you are using a development utility that generates resource IDs using
  29. UniqueResourceID, check the results to make sure no system-range resource IDs
  30. are being used by accident.  This problem is fixed in System Software 6.0.
  31.  
  32. WHAT SETCURRESOURCEFILE DOES
  33.  
  34. SetCurResourceFile is documented in Chapter 45 of the Apple IIgs Toolbox
  35. Reference, Volume 3 (see especially "Resource File Search Sequence" near the
  36. beginning of the chapter).
  37.  
  38. This explanation might make you think SetCurResourceFile rearranges the search
  39. path, but it does not; instead, it just makes searches start at a different
  40. place in the path.  SetCurResourceFile is useful for controlling what resource
  41. files are searched, not for changing the search order.
  42.  
  43.  
  44. HOW THE TOOLBOX USES RESOURCES AS TEMPLATES
  45.  
  46. The toolbox uses several types of resources as templates for creating other
  47. objects.  Examples include rControlList, rControlTemplate, and rWindParam1.
  48. The toolbox automatically releases these resources from memory as soon as it
  49. is through with them, so there is no need to create your template resources
  50. with special purge levels in an effort to free more memory.  It is not a
  51. problem.
  52.  
  53.  
  54. USING RESOURCES FROM WINDOW UPDATE ROUTINES
  55.  
  56. In System Software 6.0 and earlier there is no special code to set the current
  57. resource application when the system calls an application window update
  58. routine (See Apple IIgs Technical Note #71 for notes on NDAs and the current
  59. resource application).
  60.  
  61. To avoid a situation where a window update routine cannot get needed
  62. resources, obey the following rules:
  63.  
  64.     1. Application window update routines must either (a) assume that the
  65.        resource application has the same value it had when the window was
  66.        created, or (b) save, set, and restore the current resource
  67.        application, using GetCurResourceApp and SetCurResourceApp.
  68.  
  69.     2. NDAs that start the Resource Manager must not call application window
  70.        update routines, and they must not cause application window update
  71.        routines to be called (for example, if an NDA calls TaskMaster to
  72.        handle a modal dialog or movable modal dialog, the tmUpdate bit in
  73.        wmTaskMask must be off).
  74.  
  75. CURRESOURCEAPP IN INFODEFPROCS AND CUSTOM WINDOWS
  76.  
  77. The current resource application has no guaranteed value when an information
  78. bar definition procedure or custom window definition procedure gets control.
  79. These must always save, set, and restore the current resource application
  80. using GetCurResourceApp and SetCurResourceApp.
  81.  
  82.  
  83. STARTUPTOOLS OPENS RESOURCE FORKS READ-ONLY
  84.  
  85. When StartUpTools opens your application's resource fork, by default it opens
  86. it with read-only access.  If your application needs to make changes to the
  87. resources on disk in System Software 5.0.4 and earlier, you need to close the
  88. fork and reopen it with read and write access.  To close it, use
  89. GetCurResourceFile and CloseResourceFile; to reopen it, use LGetPathname2 and
  90. OpenResourceFile.
  91.  
  92.    Note : You must update the resFileID field in the StartStop
  93.           record if you close and reopen your resource fork.
  94.           CloseResourceFile disposes the handles of any resources
  95.           in memory from the file you're closing, so you must call
  96.           DetachResource on any resources you need to keep.  (If
  97.           you pass an rToolSTartup resource to StartUpTools, the
  98.           system detaches it for you automatically.)
  99.  
  100. In System Software 6.0 and later, setting bit 3 ($0008) of the
  101. startStopRefDesc tells the Tool Locator to open your resource fork with all
  102. allowed permissions instead of with just read permission.
  103.  
  104.  
  105. CALLING STARTUPTOOLS FROM A SHELL APPLICATION (FILE TYPE $B5, EXE)
  106.  
  107. In System Software 5.0.4 and earlier, StartUpTools tries to open the current
  108. application's resource fork.  It determines the pathname of the "current
  109. application" by examining prefix 9: and making a GET_NAME GS/OS call, but do
  110. not assume it will always construct the pathname this way.  If you call
  111. StartUpTools from a shell application and expect it to open your EXE file's
  112. resource fork, you will be disappointed.
  113.  
  114. If GS/OS has launched your application, life is good--usually, though, a shell
  115. has loaded your shell application directly, so GET_NAME returns the name of
  116. the shell instead of the name of your application file.
  117.  
  118. To open your shell file's resource fork, call ResourceStartUp, get the
  119. pathname by calling LGetPathname2 on your user ID, and pass the pathname to
  120. OpenResourceFile.  StartUpTools uses this strategy all the time in System
  121. Software 6.0 and later, meaning you don't have to.
  122.  
  123. WHAT'S NIL IN A RESOURCE MAP?
  124.  
  125. The resource maps for open resource files are kept in memory, and the
  126. structure is defined in chapter 45 of Apple IIgs Toolbox Reference, Volume 3.
  127.  
  128. The resHandle field of a resource reference record (ResRefRec) is defined as
  129. "Handle of resource in memory.  A NIL value indicates that the resource has
  130. not been loaded into memory."  In this case, NIL means that the middle two
  131. bytes of the four-byte field are zero.  In other words, a NIL entry in the
  132. resource map may have a non-zero value in the low-order byte.
  133.  
  134.  
  135. LOADRESOURCE AND SETRESLOAD(FALSE)
  136.  
  137. When you call LoadResource on a locked or fixed resource and SetResLoad is set
  138. to FALSE, you may get Memory Manager error $0204 (lockErr), because the
  139. Resource Manager tries to allocate a locked or fixed zero-length handle, which
  140. the Memory Manager does not permit.
  141.  
  142.  
  143. ADJUSTING THE SEARCH DEPTH
  144.  
  145. If you wish to add some resource files to the beginning of a resource search
  146. path and adjust the depth so that the end point of the search is unchanged,
  147. it's tempting to use SetResourceFileDepth(0) to get the current depth, add
  148. one, and set this new depth with SetResourceFileDepth.
  149.  
  150. The problem is that the search depth is often -1 ($FFFF), meaning "search
  151. until the end of the chain."  If you add your adjustment to -1, you do not
  152. usually get the intended effect.  A solution is just to check for $FFFF and
  153. not adjust the depth in that case.
  154.  
  155.  
  156. CURRESOURCEAPP AFTER RESOURCESHUTDOWN
  157.  
  158. After a ResourceShutDown call, the current resource application is always
  159. $401E.  (The Resource Manager starts itself up at boot time with its own
  160. memory ID, $401E.  Do not ever call ResourceShutDown while the current
  161. resource application is $401E.)
  162.  
  163.  
  164. RESTORING THE CURRESOURCEAPP
  165.  
  166. If you need to start up and shut down the Resource Manager without disturbing
  167. the current resource application, call GetCurResourceApp before
  168. ResourceStartUp, and call SetCurResourceApp to restore the old value after
  169. ResourceShutDown.
  170.  
  171. It does not help to call GetCurResourceApp after ResourceStartUp, since the
  172. application just started up is always the current resource application.
  173.  
  174. Shell programs which start the Resource Manager need to call SetCurResourceApp
  175. after regaining control from a subprogram (for example, an EXE file) which may
  176. have started and shut down the Resource Manager, leaving the current resource
  177. application set to $401E instead of the shell's ID.
  178.  
  179. Shell programs that do not start the Resource Manager have nothing to worry
  180. about.  In this case the current resource application is normally $401E, so
  181. when a subprogram calls ResourceShutDown life is still wonderful.
  182.  
  183.  
  184. WHAT INFORMATION IS KEPT FOR EACH RESOURCE APPLICATION?
  185.  
  186. When you switch resource applications with SetCurResourceApp, that takes care
  187. of all the application-specific information the Resource Manager has.
  188.  
  189. There is no need to separately preserve the current resource file, the search
  190. depth, the SetResourceLoad setting, or any application resource converters
  191. that are logged in.  All of this information is already recorded separately
  192. for each resource application.
  193.  
  194.  
  195. "CHANGED" IS A RESOURCE ATTRIBUTE
  196.  
  197. This seems obvious when first reading the documentation, but it has a
  198. consequence that isn't so obvious.
  199.  
  200. If you mark a resource as changed with MarkResourceChanged and later use
  201. SetResourceAttr to change that resource's attributes, you must include
  202. resChanged in the attributes you specify or the Resource Manager does not
  203. still know the resource has changed.
  204.  
  205. This means you can undo a MarkResourceChanged call, but it also means you need
  206. to preserve the resChanged bit across SetResourceAttr calls if you don't want
  207. to accidentally achieve the same effect.
  208.  
  209. The Resource Manager clears the resChanged attribute when a resource is
  210. written to disk; the attribute indicates the data in memory is more recent
  211. than what's on disk.  Normally, adding a resource with AddResource sets this
  212. bit because the resource isn't actually written to disk until the resource
  213. file is updated.
  214.  
  215. However, if AddResource has to make the file longer (by extending the EOF), it
  216. writes the resource to disk immediately.  This means that in some cases, a
  217. resource added with AddResource will be properly added but the resChanged
  218. attribute will not be set.  Don't be confused if this happens to you.
  219.  
  220.  
  221. MAKING RESOURCE MANAGER CALLS FROM RESOURCE CONVERTERS
  222.  
  223. Don't.  This would be a first-class example of reentrancy, and the Resource
  224. Manager is not reentrant in any class.
  225.  
  226.  
  227. WHO OWNS HANDLES PASSED TO ADDRESOURCE?
  228.  
  229. When you pass a handle to AddResource, the Resource Manager is responsible for
  230. the handle unless AddResource returns an error.  Once you call AddResource,
  231. the handle belongs to the Resource Manager and you must treat it like you
  232. would the handle to any other resource.
  233.  
  234.  
  235. NAMED RESOURCE BUGS IN SYSTEM SOFTWARE 6.0
  236.  
  237. The new-for-6.0 Resource Manager function RMFindNamedResource compares the
  238. resource name you requested to named resources incorrectly.  The comparison
  239. algorithm doesn't compare the lengths of the strings before starting to
  240. compare the characters.  This means, for example, that if you request a
  241. resource named "Raymond" and the Resource Manager encounters a named resource
  242. named "Raymond" first, it will return the resource named "Raymond" instead.
  243. This anomaly also affects the HyperCard IIgs named-resource XCMD callback
  244. functions, even though they don't use the Resource Manager's named-resource
  245. calls.
  246.  
  247. This anomaly also affects RMLoadNamedResource, which calls
  248. RMFindNamedResource.
  249.  
  250. DEBUGGING INFORMATION
  251.  
  252. The following information is provided for your convenience during program
  253. development.  It allows you to check exactly what user IDs are using the
  254. Resource Manager, what files are in their search paths, and what resource
  255. converters are logged in.
  256.  
  257. DO NOT depend on this information in your program; it is subject to change in
  258. future versions of the Resource Manager.
  259.  
  260. All the Resource Manager's data structures are rooted in the Resource Manager
  261. tool set's Work Area Pointer (WAP).  To get the Resource Manager's WAP, call
  262. GetWAP (in the Tool Locator) with userOrSystem = $0000 and tsNum = $001E.
  263.  
  264. The WAP value is a handle to the Resource Manager's block of global data.
  265. Several interesting areas in this block are listed below.
  266.  
  267.    +$0A2  curApp         Word   Offset into the globals block of the current
  268.                                 resource application's Application Record.
  269.    +$2B0  sysFile        Long   Handle of system file map, or NIL if none.
  270.    +$2B4  sysConvertList Long   Handle of system converter list, or NIL if
  271.                                 none.
  272.    +$2B8  appList  20*n bytes   List of Application Records (20 bytes each).
  273.  
  274.  
  275. Each Application Record has this format:
  276.  
  277.    +000   appFlag        Word   0=entry available, 1=entry used, $FFFF = end
  278.                                 of array.
  279.    +002   appID          Word   User ID of application.
  280.    +004   appFiles       Long   Handle of application's first resource map,
  281.                                 NIL=none.
  282.    +008   appCur         Long   Handle of application's current resource map,
  283.                                 NIL=none.
  284.    +012   appConverters  Long   Handle of application's converter list,
  285.                                 NIL=none.
  286.    +016   appReadFlag    Word   1=read resources, 0=don't read
  287.                                 (SetResourceLoad).
  288.    +018   appFileDepth   Word   Number of files to search in this path.
  289.  
  290.  
  291. Converter lists have this format:
  292.  
  293.    +000    n            Word        Number of entries in the table (entries
  294.                                     can be unused).
  295.    +002   theConverters 6*n bytes   List of converter entries (6 bytes each).
  296.  
  297.  
  298. Each Converter entry has this format:
  299.  
  300.    +000  resType      Word     Resource type for this converter ($0000 for
  301.                                unused entry).
  302.    +002  convAddress  Long     Address of resource converter.
  303.  
  304. The format for a resource map is described starting on page 45-17 of Apple
  305. IIgs Toolbox Reference, Volume 3.
  306.  
  307. Remember, don't depend on this information in your application; use it during
  308. debugging, and use it to write debugging utilities.
  309.  
  310.  
  311. Further Reference
  312. _____________________________________________________________________________
  313.  
  314.    o   Apple IIgs Toolbox Reference, Volume 3
  315.    o   Apple IIgs Technical Note #71, DA Tips and Techniques
  316.  
  317.